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Security Negotiation for WebNFS 
Status of this Memo 
This memo provides information for the Internet community. It does 
not specify an Internet standard of any kind. Distribution of this 
memo is unlimited. 
Copyright Notice 
Copyright (C) The Internet Society (2000). All Rights Reserved. 
Abstract 
This document describes a protocol for a WebNFS client [RFC2054] to 
negotiate the desired security mechanism with a WebNFS server 
[RFC2055] before the WebNFS client falls back to the MOUNT v3 
protocol [RFC1813]. This document is provided so that people can 


write compatible implementations. 
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1. Introduction 


The MOUNT protocol is used by an NFS client to obtain the necessary 
filehandle for data access.  MOUNT versions 1 and 2 [RFC1094] return 
NFS version 2 filehandles, whereas MOUNT version 3 [RFC1813] returns 
NFS version 3 filehandles. 


Among the existing versions of the MOUNT protocol, only the MOUNT v3 
provides an RPC procedure (MOUNTPROC3 MNT) which facilitates security 
negotiation between an NFS v3 client and an NSF v3 server. When this 
RPC procedure succeeds (MNT3 OK) the server returns to the client an 
array of security mechanisms it supports for the specified pathname, 
in addition to an NFS v3 filehandle. 


A security mechanism referred to in this document is a generalized 
security flavor which can be an RPC authentication flavor [RFC1831] 
or a security flavor referred to in the RPCSEC GSS protocol 
[RFC2203]. A security mechanism is represented as a four-octet 
integer. 


No RPC procedures are available for security negotiation in versions 
1 or 2 of the MOUNT protocol. 


The NFS mount command provides a "sec=" option for an NFS client to 
specify the desired security mechanism to use for NFS transactions. 
If this mount option is not specified, the default action is to use 
the default security mechanism over NFS v2 mounts, or to negotiate a 
security mechanism via the MOUNTPROC3_MNT procedure of MOUNT v3 and 
use it over NFS v3 mounts. In the latter, the client picks the first 
security mechanism in the array returned from the server that is also 
supported on the client. 


As specified in RFC 2054, a WebNFS client first assumes that the 
server supports WebNFS and uses the publsc filehandle as the initial 
filehandle for data access, eliminating the need for the MOUNT 
protocol. The WebNFS client falls back to MOUNT if the server does 
not support WebNFS. 


Since a WebNFS client does not use MOUNT initially, the 
MOUNTPROC3 MNT procedure of MOUNT v3 is not available for security 
negotiation until the WebNFS client falls back to MOUNT. A viable 
protocol needs to be devised for the WebNFS client to negotiate 
security mechanisms with the server in the absence of the 
MOUNTPROC3 MNT procedure. 
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The WebNFS security negotiation protocol must meet the following 
requirements: 


- Must work seamlessly with NFS v2 and v3, and the WebNFS 
protocols 


- Must be backward compatible with servers that do not support 
this negotiation 


- Minimum number of network turnarounds (latency) 


This document describes the WebNFS security negotiation protocol 
developed by Sun Microsystems, Inc. Terminology and definitions from 
RFCs 2054 and 2055 are used in this document. The reader is expected 
to be familiar with them. 


2. Security Negotiation Multi-component LOOKUP 


The goal of the WebNFS security negotiation is to allow a WebNFS 
client to identify a security mechanism which is used by the WebNFS 
server to protect a specified path and is also supported by the 
client. The WebNFS client initiates the negotiation by sending the 
WebNFS server the path. The WebNFS server responds with the array of 
security mechanisms it uses to secure the specified path. From the 
array of security mechanisms the WebNFS client selects the first one 
that it also supports. 


Without introducing a new WebNFS request, the WebNFS security 
negotiation is achieved by modifying the request and response of the 


existing multi-component LOOKUP (MCL) operation [RFC2055]. Note that 
the MCL operation is accomplished using the LOOKUP procedure 
(NFSPROC3 LOOKUP for NFS v3 and NFSPROC LOOKUP for NFS v2). This and 


the next sections describe how the MCL request and response are 
modified to facilitate WebNFS security negotiation. 


For ease of reference, the modified MCL request is henceforth 
referred to as SNEGO-MCL (security negotiation multi-component 
LOOKUP) request. 


A multi-component LOOKUP request [RFC2055] is composed of a public 
filehandle and a multi-component path: 


For Canonical Path: 


LOOKUP FH-0x0, "/a/b/c" 
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For Native Path: 
LOOKUP FH=0x0, 0x80 "a:b:c" 


A multi-component path is either an ASCII string of slash separated 
components or a 0x80 character followed by a native path. Note that 
a multi-component LOOKUP implies the use of the public filehandle in 
the LOOKUP. 


Similar to the MCL request, a SNEGO-MCL request consists of a public 
filehandle and a pathname. However, the pathname is uniquely 
composed, as described below, to distinguish it from other pathnames. 


The pathname used in a SNEGO-MCL is the regular WebNFS multi- 
component path prefixed with two octets. The first prefixed octet is 
the 0x81 non-ascii character, similar to the 0x80 non-ascii character 
for the native paths. This octet represents client’s indication to 
negotiate security mechanisms. It is followed by the security index 
octet which stores the current value of the index into the array of 
security mechanisms to be returned from the server. The security 
index always starts with one and gets incremented as negotiation 
continues. It is then followed by the pathname, either an ASCII 
string of slash separated canonical components or 0x80 and a native 
path. 


A security negotiation multi-component LOOKUP request looks like 
this: 


For Canonical Path: 
LOOKUP FH-0x0, 0x81 «sec-index» "/a/b/c" 
For Native Path: 
LOOKUP FH-0x0, 0x81 «sec-index» 0x80 "a:b:c" 


In the next section we will see how the MCL response is modified for 
WebNFS security negotiation. 


3. Overloaded Filehandle 


As described in RFC2054, if a multi-component LOOKUP request 
succeeds, the server responds with a valid filehandle: 


LOOKUP FH-0x0, "a/b/c" 


FH=0x3 
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NFS filehandles are used to uniquely identify a particular file or 
directory on the server and are opaque to the client. The client 
neither examines a filehandle nor has any knowledge of its contents. 
Thus, filehandles make an ideal repository for the server to return 
the array of security mechanisms to the client in response to a 
SNEGO-MCL request. 


To a successful SNEGO-MCL request the server responds, in place of 
the filehandle, with an array of integers that represents the valid 
Security mechanisms the client must use to access the given path. A 
length field is introduced to store the size (in octets) of the array 
of integers. 


As the filehandles are limited in size (32 octets for NFS v2 and up 
to 64 octets for NFS v3), it can happen that there are more security 
mechanisms than the filehandles can accommodate. To circumvent this 
problem, a one-octet status field is introduced which indicates 
whether there are more security mechanisms (1 means yes, 0 means no) 
that require the client to perform another SNEGO-MCL to get them. 


To summarize, the response to a SNEGO-MCL request contains, in place 
of the filehandle, the length field, the status field, and the array 
of security mechanisms: 


FH: length, status, (sec 1 sec 2 ... sec n] 


The next two sub-sections describe how NFS v2 and v3 filehandles are 
"overloaded" to carry the length and status fields and the array of 
security mechanisms. 


3.1 Overloaded NFS Version 2 Filehandle 


A regular NFS v2 filehandle is defined in RFC1094 as an opaque value 
occupying 32 octets: 


1 2 3 4 32 
R---—4R---4---4---4---4---4---4---—4 R---—4R---4---4---4---4---4---—4 


R---—4R---4---4---4---4---4---4---—4 R---—4R---4---4---4---4---4---—4 


An overloaded NFS v2 filehandle looks like this: 


si 2 3 4 5 8 32 
T-—-—4---4---—4---—------—4---—--- T---—4---4---4---— T---—4---* 
| L | S | | | sec 1 | s sec n xs | | 
T-——---4---—4---—---4---—4---—4--- T---—---4---—4---— T---—4---* 
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Note that the first four octets of an overloaded NFS v2 filehandle 
contain the length octet, the status octet, and two padded octets to 
make them XDR four-octet aligned. The length octet 1 = 4 * n, where 
n is the number of security mechanisms sent in the current overloaded 
filehandle. Apparently, an overloaded NFS v2 filehandle can carry up 
to seven security mechanisms. 


3.2 Overloaded NFS Version 3 Filehandle 


A regular NFS v3 filehandle is defined in RFC1813 as a variable 
length opaque value occupying up to 64 octets. The length of the 
filehandle is indicated by an integer value contained in a four octet 
value which describes the number of valid octets that follow: 


1 4 
4+---+---+---+---+4+ 
len 
4R---—4---4---4--- 


J; 4 up to 64 
4-—-—4---4---4---4---4---4---4---4---4---4---4--- F---4---4---4---M 
Gan come) Me Ge» Vs (Oe out. Mese s desees ME. Au. Oe d 
4-—-—4---4---4---4---4---4---4---4---4---4---4--- T---4---4---4---M 


An overloaded NFS v3 filehandle looks like the following: 


al 4 
4R---—4---4---4--- 
len | 
4R---—4---4---4--- 


X 4 5 8 
+—---+---+---+---+---+---+---+---+ +---+---+---+---+ 
|s | | | | sec 1 EFE sec_n 
+---+---4---4+---+---+---4---4+---+ +---+---4---4+---+ 
Here, len = 4 * (n+1). Again, n is the number of security mechanisms 
contained in the current overloaded filehandle. Three octets are 


padded after the status octet to meet the XDR four-octet alignment 
requirement. An overloaded NFS v3 filehandle can carry up to fifteen 
security mechanisms. 


4. WebNFS Security Negotiation 
With the SNEGO-MCL request and the overloaded NFS v2 and v3 


filehandles defined above, the following diagram depicts the WebNFS 
security negotiation protocol: 
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Client Server 


LOOKUP FH-0x0, 0x81 <sec-index> "path" 


FH: length, status, (sec 1 sec 2 ... sec n] 


where 
0x81 represents client's indication to negotiate security 
mechanisms with the server, 


path is either an ASCII string of slash separated components or 
0x80 and a native path, 


Sec-index, one octet, contains the index into the array of 
security mechanisms the server uses to protect the specified path, 


status, one octet, indicates whether there are more security 
mechanisms (1 means yes, 0 means no) that require the client to 
perform another SNEGO-MCL to get them, 


length (one octet for NFS v2 and four octets for NFS v3) describes 
the number of valid octets that follow, 


(sec 1 sec 2 ... sec n) represents the array of security 
mechanisms. As noted earlier, each security mechanism is 
represented by a four-octet integer. 
Here is an example showing the WebNFS security negotiation protocol 
with NFS v2. In the example it is assumed the server shares /export 
with 10 security mechanisms {0x3900 0x3901 0x3902 ... 0x3909} on the 
export, two SNEGO-MCL requests would be needed for the client to get 
the complete security information: 


LOOKUP FH=0x0, 0x81 0x01 "/export" 


Oxlc, 0x01, {0x3900 0x3901 0x3902 0x3903 0x3904 0x3905 0x3906} 


LOOKUP FH-0x0, 0x81 0x08 "/export" 


0xOc, 0x00, {0x3907 0x3908 0x3909} 
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The order of the security mechanisms returned in an overloaded 
filehandle implies preferences, i.e., one is more recommended than 
those following it. The ordering is the same as that returned by the 
MOUNT v3 protocol. 


The following shows a typical scenario which illustrates how the 
WebNFS security negotiation is accomplished in the course of 
accessing publicly shared filesystems. 


Normally, a WebNFS client first makes a regular multi-component 
LOOKUP request using the public filehandle to obtain the filehandle 
for the specified path. Since the WebNFS client does not have any 
prior knowledge as to how the path is protected by the server the 
default security mechanism is used in this first multi-component 
LOOKUP. If the default security mechanism does not meet server's 
requirements, the server replies with the AUTH TOOWEAK RPC 
authentication error, indicating that the default security mechanism 
is not valid and the WebNFS client needs to use a stronger one. 


Upon receiving the AUTH TOOWEAK error, to find out what security 
mechanisms are required to access the specified path the WebNFS 
client sends a SNEGO-qMCL request, using the default security 
mechanism. 


If the SNEGO-MCL request succeeds the server responds with the 
filehandle overloaded with the array of security mechanisms required 
for the specified path. If the server does not support WebNFS 
security negotiation, the SNEGO-MCL request fails with NFSERR IO for 
NFS v2 or NFSS3ERR IO for NFS v3 [RFC2055]. 


Depending on the size of the array of security mechanisms, the WebNFS 
client may have to make more SNEGO-MCL requests to get the complete 
array. 


For successful SNEGO-MCL requests, the WebNFS client retrieves the 
array of security mechanisms from the overloaded filehandle, selects 
an appropriate one, and issues a regular multi-component LOOKUP using 
the selected security mechanism to acquire the filehandle. 


All subsequent NFS requests are then made using the selected security 
mechanism and the filehandle. 


The following depicts the scenario outlined above. It is assumed 
that the server shares /export/home as follows: 


share -o sec-sec 1:sec 2:sec 3,public /export/home 
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and AUTH SYS is the client's default security mechanism and is not 
one of (sec 1, sec 2, sec 3J. 


Client Server 


LOOKUP FH-0x0, "/export/home" 
AUTH SYS 


AUTH TOOWEAK 
LOOKUP FH-0x0, 0x81 0x01 "/export/home" 


AUTH SYS 


overloaded FH: length, status, (sec 1 sec 2 sec 3) 


LOOKUP FH=0x0, "/export/home" 
sec_n 


NFS request with FH=0x01 


In the above scenario, the first request is a regular multi-component 
LOOKUP which fails with the AUTH_TOOWEAK error. The client then 
issues a SNEGO-MCL request to get the security information. 


There are WebNFS implementations that allow the public filehandle to 
work with NFS protocol procedures other than LOOKUP. For those 
WebNFS implementations, if the first request is not a regular multi- 
component LOOKUP and it fails with AUTH TOOWEAK, the client should 
issue a SNEGO-MCL with 

0x81 0x01 "." 


as the path to get the security information. 
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5. Security Considerations 


The reader may note that no mandatory security mechanisms are 
Specified in the protocol that the client must use in making SNEGO- 
MCL requests. Normally, the client uses the default security 
mechanism configured on his system in the first SNEGO-MCL request. 

If the default security mechanism is not valid the server replies 
with the AUTH TOOWEAK error. In this case the server does not return 
the array of security mechanisms to the client. The client can then 
make another SNEGO-MCL request using a stronger security mechanism. 
This continues until the client hits a valid one or has exhausted all 
the supported security mechanisms. 
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9. Full Copyright Statement 
Copyright (C) The Internet Society (2000). All Rights Reserved. 


This document and translations of it may be copied and furnished to 
others, and derivative works that comment on or otherwise explain it 
or assist in its implementation may be prepared, copied, published 
and distributed, in whole or in part, without restriction of any 
kind, provided that the above copyright notice and this paragraph are 
included on all such copies and derivative works. However, this 
document itself may not be modified in any way, such as by removing 
the copyright notice or references to the Internet Society or other 
Internet organizations, except as needed for the purpose of 
developing Internet standards in which case the procedures for 
copyrights defined in the Internet Standards process must be 
followed, or as required to translate it into languages other than 
English. 


The limited permissions granted above are perpetual and will not be 
revoked by the Internet Society or its successors or assigns. 


This document and the information contained herein is provided on an 
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 
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